docs(gh-cli): GITHUB_TOKEN per-repo rate limit + git-tree workaround#106
Conversation
…workaround The GITHUB_TOKEN in Actions is capped at 1,000 REST requests/hour per repository. A workflow probing many paths across many repos exhausts it, and the failure misleads: the build job passes while the deploy job 403s. Add a "Rate Limits" section to gh-cli-reference.md covering the cap, the build-green/deploy-403 symptom, and the fix — one recursive git-trees call per repo instead of N per-file contents probes (drops a ~100-repo sweep from ~1,500 calls to a few hundred), plus the free rate_limit preflight. Came from a /retro sweep of session 44c102fc (2026-07-04): a TYPO3 docs dashboard's nightly Pages deploy 403'd on this exact limit. Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
github-actions
Bot
added
documentation
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds a new section to the GitHub CLI reference documentation explaining GITHUB_TOKEN rate limits in GitHub Actions and providing optimized commands to fetch git trees recursively. The review feedback suggests improving the robustness of the provided jq commands by using optional chaining and default fallbacks to handle potentially null or missing JSON fields safely.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
There was a problem hiding this comment.
Pull request overview
Adds guidance to the GitHub CLI reference documentation to help workflows avoid exhausting the GITHUB_TOKEN REST API rate limit, including a recommended git/trees?recursive=1-based approach to reduce per-file contents probing.
Changes:
- Documented the
GITHUB_TOKENREST rate limit behavior in Actions and a common “build green / deploy 403” symptom. - Added an example workflow pattern for enumerating repo files via the Git data “tree” API instead of per-file
contentscalls. - Documented a
rate_limitpreflight check before running large collectors.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Review feedback on #106: - Fix subject-verb agreement ("Actions injects"). - Clarify the 1,000/hr cap is charged to the token issued for the WORKFLOW's repository and shared across all its calls, including calls to other repos — not a separate per-target-repo budget (which is what "per repository" implied). - Drop the commits lookup: git/trees resolves a ref directly, so the example is now genuinely one call per repo (verified against a live repo). - Null-safe jq (.tree[]?, .resources.core? // empty). Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
|
Summary
Document the
GITHUB_TOKENper-repository REST rate limit (1,000/hour) and the git-tree API workaround, inreferences/gh-cli-reference.md.Came from
/retrosweep on 2026-07-05 of session44c102fc(2026-07-04).Finding: B16 (hard-won technique) — a nightly GitHub Pages deploy 403'd because a collector fired ~1,500
contentsprobes across ~100 repos, exhausting the installation token's per-repo cap. Thebuildjob passed whiledeployfailed, which misdirected debugging.Change
New "Rate Limits — GITHUB_TOKEN in Actions" section covering:
git/trees?recursive=1call per repo instead of N per-filecontentsprobes (~1,500 → a few hundred calls);rate_limitpreflight.Test plan
git/trees?recursive=1example runs and lists blob paths as written